---
id: secrets-key-rotation
title: Secrets and Key Rotation
---

There are two types of key rotation:

- Rotation of JSON Web Token Signing Keys
- Rotation of HMAC Token Signing and Database and Cookie Encryption Keys

### Rotation of JSON Web Token Signing Keys

JSON Web Token Signing Key rotation is simple with Ory Hydra. You can rotate
OpenID Connect ID Token and OAuth 2.0 Access Tokens, when using the JSON Web
Token strategy, keys with one simple command.

Ory Hydra takes the latest key from the key store to sign JSON Web Tokens. All
public keys will be shown at
`http://ory-hydra-public-api/.well-known/jwks.json`.

#### OpenID Connect ID Token

```
hydra keys create --endpoint=http://ory-hydra-admin-api/ hydra.openid.id-token -a RS256
```

#### OAuth 2.0 Access Tokens (JSON Web Token)

> This will only work when using the JWT access token strategy. Otherwise, this
> will have no effect.

```
hydra keys create --endpoint=http://ory-hydra-admin-api/ hydra.jwt.access-token -a RS256
```

### Rotation of HMAC Token Signing and Database and Cookie Encryption Keys

Rotating database encryption keys is done by prepending the new encryption key
to the respective configuration value. Assuming configuration

```yaml
secrets:
  cookie:
    - the-old-cookie-encryption-key
  system:
    - the-old-system-encryption-key
```

one would add the new keys as follows

```yaml
secrets:
  cookie:
    - the-new-cookie-encryption-key # the new key must be the first entry
    - the-old-cookie-encryption-key
  system:
    - the-new-system-encryption-key # the new key must be the first entry
    - the-old-system-encryption-key
```

> It is very important that the new key is the first entry in the list as only
> the first key is used for encryption while all keys from the list are used for
> decryption. Please note that existing data will not be automatically
> re-encrypted using the new key. Only new data will be signed and encrypted
> using the new key. It is therefore imperative that the old key is added to the
> list, unless you want to also invalidate all data that was signed or encrypted
> using the old key.
